Copyright (C) 1993 Mark R. Rinfret, MRsoftware

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

MRMan

Online Manual Browser for the Amiga Version 1.0.0 March 1993

by Mark R. Rinfret

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1993 Mark R. Rinfret

1 Permissions

MRMan is freely distributable shareware. It may be redistributed via magnetic media or electronic bulletin board systems (BBS). It is unlawful to charge a fee for this software other than reasonable distribution/media fees.

The author assumes no responsibilty for damages incurred as a result of using MRMan. USE AT YOUR OWN RISK! No warranties, either expressed or implied, are made with regard to its use on any system.

Once you have tried MRMan and have decided to continue using it, you are requested to submit five dollars ($5.00 U.S.) to the author. You should also provide the following information:

         Your mail address
         Your e-mail address(es), if any
         The version of MRMan you are registering

Send this to:

         MRsoftware
         348 Indian Avenue
         Portsmouth, RI  02871

2 MRMan User’s Manual

2 Overview

MRMan is a document browsing tool for the Amiga family of computers. Though it borrows part of its name from the Un*x man command, it’s actually quite different in its operation.

MRMan will let you store your online documents in any location - in a separate document hierarchy, in multiple hierarchies spread out over multiple partitions, in the same directories as the associated programs, etc.

MRMan also supports multiple document types and compressed document files (a la the Un*xcompatible compress command). Generally speaking, MRMan uses the filename suffix (extension following a period) to distinguish document types. Documents not having an explicit type (.doc, .text, .guide, etc.) fall into the default class. A special filename suffix, ‘.Z’, is recognized as an indication that the file has been compressed with the Un*x compress program. This compression may have been performed on a Un*x platform or with an Amiga-compatible version of the program (available at various Internet sites and in the Fred Fish library). In this case, the ‘.Z’ suffix is ignored and MRMan looks for a preceding suffix.

MRMan currently relies on two environment variables, ‘ENV:MRMan/ManPath’ and ‘ENV:MRMan/Config’ to tailor its operation to your system (see Section 3.4 [Installing MRMan], page 6).

4 MRMan User’s Manual

3 Installing MRMan

3.1 Unpacking the MRMan Archive

You most likely received MRMan as an Lha archive. It will unpack into its own directory hierarchy with the following command:

     lha -xa x MRMan.lha

The actual archive name may vary from ‘MRMan.lha’ since it may include a version number. If the archive is unpacked correctly, a new directory will be created containing the MRMan program, documentation and environment variable directories.

3.2 Installing the Software

Make the MRMan directory the current directory by using the CD command.

You can install the MRMan program in any suitable directory which is a part of your command search path (i.e. defined by the AmigaDOS PATH command). For example, if you have a directory named ‘SYS:Bin’, you could copy the MRMan program there with

     COPY CLONE MRMan SYS:Bin

It is assumed that you have at least one directory on your system where document files are stored (though this is not a requirement). It is quite likely that you have several documentation directories (quite likely not sharing a common hierarchy).

The documentation for MRMan comes in three forms:

• A plain text file named ‘MRMan.doc’

• An AmigaGuide(tm) file named ‘MRMan.guide’

• A TeX ‘DVI’ file named ‘MRMan.dvi’.

Copy any or all of these to the appropriate online documentation area.

3.3 Edit the ManPath Environment Variable

The ‘ManPath’ environment variable is stored in a file in the MRMan installation directory named ‘Env/MRMan/ManPath’. This file contains a list of volume, directory or logical names (not file names) where online documentation may be found. The format of this file is one name per line. Example:

 man:
 uucp:man
 MR0:Debug
 AutoDocs:

The ‘Manpath’ environment variable directs MRMan to search in the specified volumes or directories for documents when building its index.

3.4 Edit the Config Environment Variable

The ‘Config’ environment variable is stored in a file in the MRMan installation directory named ‘Env/MRMan/ManPath’. This file contains various MRMan configuration data which customizes its behavior to your unique requirements.

The ‘Config’ variable appears as a text file with lines of comments (lines beginning with a semi-colon) interspersed with lines of directives. The following directives are currently supported:

index = index file name This instructs MRMan to maintain its document index in the file specified by index file name. defaultviewer = viewer name This provides the name of a document viewing program, viewer name, to be used for documents which have no specific type (filename suffix). If the viewer program can always be located via the command search path in effect when the MRMan command is issued, only its simple name must be given. However, if the viewer program is stored in a directory which is not in the command search path, the full name must be specified. suffix = suffix name viewer name This directive specifies a legal document file suffix and the name of the viewing program which should be used with this file. If the viewer program can always be located via the command search path in effect when the MRMan command is issued, only its simple name must be given. However, if the viewer program is stored in a directory which is not in the command search path, the full name must be specified.

; Define where the MRMan index is stored:
index = MAN:MRMan.index
;
; Define the default viewer for filenames which have no suffixes.
defaultviewer = Multiview
;
; Declare the legal suffixes for MRMan.
; The format for these entries is:
;   suffix = <suffix_name> [ <viewer_name> ]
;
; The suffix name must not include the preceding period.
; The <viewer_name> may be either the full name of the viewing program
; to be used or a name that is relative to your current search path.
;
suffix = guide  MultiView
;
; If you don't have MultiView, you might use this entry for
; AmigaGuide:
;
; suffix = guide SYS:Utilities/AmigaGuide
;
suffix = doc    More
suffix = man    More
suffix = text   More
;

Once these changes are made, copy the environment variable directory to both the ENV: and ENVARC: directories:

COPY CLONE ALL Env ENV:
COPY CLONE ALL Env ENVARC:

Whenever you make changes to your MRMan environment variables, remember to copy the ENV:MRMan directory to ENVARC:. Otherwise, your changes will be lost the next time you reboot your system.

8 MRMan User’s Manual

You’re almost ready to use MRMan, but first, you’ll have to build the index (see Chapter 4 [Building the Index], page 9).

4 Building the Index

To speed up MRMan’s operation, an index of all available online documentation is built in advance. Presently, this index file is a very simple flat text file consisting of two fields per line: the subject name and the full name of the document associated with that subject. These entries are nonunique. That is, several entries may exist for a given subject. This topic is discussed in another chapter (see Chapter 5 [MRMan Browser Mode], page 11).

The first time you build the index, you should do it manually to make sure that you haven’t made any typographical errors in your ManPath environment variable. Just do the following:

     mrman VERBOSE INDEX

The ‘VERBOSE’ option turns on verbose mode. In verbose mode, MRMan will report every directory scanned and every document file recognized. The ‘INDEX’ option directs MRMan to build the index. Once the index is built, you can use MRMan in its browse mode to locate and view your online documents.

It should be apparent that the MRMan index is only as current as you keep it. If you add or delete documents but don’t rebuild the index, inaccuracies will result. MRMan won’t know about some documents and will attempt to locate others that don’t exist. It is highly recommended that you rebuild the index, either by manually invoking MRMan whenever you make a change to your document set or by running MRMan periodically via an automatic software scheduling program such as dcron, AmiCron or others. Programs of this type are available via the Fred Fish library and many bulletin board systems and ftp sites.

10 MRMan User’s Manual

5 MRMan Browser Mode

MRMan has two methods of locating documents:

• Show documents for specific subject(s) or subject patterns

• Present a ’shopping list’ of all available documents

Using the first method, MRMan attempts to locate any documents whose base name (the portion preceding the filename suffix) matches the desired subject. You may specify an exactly worded subject (e.g. dos, enforcer, mrman, etc.) or you may use an AmigaDOS pattern (no directory components). If more than one subject matches the pattern, a requester will pop up and display a list of all documents for which there was a match. A single click of the mouse on a list entry will cause the document to be displayed. Here’s an example:

     mrman #?graphics#?

You should know that MRMan performs a case-insensitive (A=a) comparison of the pattern you specify against the subjects it finds. You can read more about AmigaDOS pattern matching in "The AmigaDOS Manual, Third Edition", chapter 6, "Calling AmigaDOS" under the description for the MatchFirst function (congratulations to whomever managed to bury this important information in such an obscure location!).

Using the second method, MRMan simply presents all subjects to the user in the form of a scrollable list and lets the user pick and choose.

To use MRMan in the first mode, simply issue a command of the form:

mrman subject [ . . .... subject ]

Notice that more than one subject may be specified in a single invocation of MRMan. For each subject specified, mrman will search its index and present the associated documentation, using either the default document viewer or the one specified by the suffix directive (see Section 3.4 [Installing MRMan], page 6) for the document’s file type. If the document was compressed (has a ‘.Z’ suffix), it will first be decompressed to a temporary file. This temporary file will be deleted once viewing is terminated.

If MRMan should locate more than one document for a given subject, a pop-up window will open. This window will present a list of all the documents which were found for the specified subject. The user may select any of these for viewing simply by clicking the mouse over the appropriate entry in the scrolling list. When viewing has been completed, the list reappears. When the user is done viewing all documentation on the subject, he/she indicates this by clicking on the Cancel gadget near the bottom of the window.

To use the ’shopping list’ mode, simply invoke MRMan without any arguments:

     mrman

6 Things to Do

I intend to evolve and improve MRMan over time. Your input will be greatly appreciated. Some of the changes planned (not necessarily in any particular order) are:

• More sophisticated index While the current approach is adequate for installations having a few hundred documents or less online, it probably will suffer on much larger systems. I’ll probably move toward a hashed lookup scheme if someone presents some justification. Even nicer would be a "keyword-in-context" index but that may result in a major effort.

• Automatic partial index updating. By checking the modification dates on just the document directories, MRMan could (according to user preferences) update just the parts of the index which require changing. Of course, this also would require a more sophisticated index structure.

14 MRMan User’s Manual Concept Index 15

Concept Index

B

Browser Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Browsing All Subjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Browsing Specific Subjects . . . . . . . . . . . . . . . . . . . . . . . . . 11 Building the Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

E

Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

I

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

O

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

P

Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Plans for the Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

T

The Config Environment Variable . . . . . . . . . . . . . . . . . . . 6 The ManPath Environment Variable . . . . . . . . . . . . . . . . 6

16 MRMan User’s Manual

Short Contents

1 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 Installing MRMan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4 Building the Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5 MRMan Browser Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6 Things to Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

ii MRMan User’s Manual

Table of Contents

1 Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 Installing MRMan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1 Unpacking the MRMan Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 Installing the Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.3 Edit the ManPath Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.4 Edit the Config Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 Building the Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5 MRMan Browser Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6 Things to Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Concept Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

iv MRMan User’s Manual